Actualizar el análisis Marshal

Este endpoint solicita un nuevo análisis Marshal para un RUT ya cargado en tu cuenta. Marshal complementa el compliance del RUT con hallazgos en medios de prensa y detección de Personas Expuestas Políticamente (PEP).

• Requiere que tu plan cuente con Marshal e incluya el ayudante Compliance.
• El RUT debe estar cargado en tu cuenta. Para cargarlo y solicitar el análisis en un solo paso, usa Carga de RUT con includeMarshal.
• El cobro se aplica conforme a tu acuerdo comercial. Si el RUT está en monitoreo y todavía no tenía Marshal, la solicitud lo incorpora al monitoreo de Marshal y el cobro se aplica en ese momento, aunque el análisis falle. En los demás casos, el análisis se cobra cuando se completa; si falla, no se cobra.
• La solicitud es asíncrona: la respuesta confirma que se recibió y el análisis se procesa en los minutos siguientes (ver Cómo funciona).

Qué cambia respecto a la v2

Endpoint nuevo en la v3: la v2 no permite solicitar análisis Marshal. Ver la Guía de Migración.

Detalle de API

Request

• URL: /helper/compliance/{rut}/actualizarMarshal
• Método: POST

Parámetros de ruta (path)

Valor	Tipo	Es requerido	Descripción
rut	string	Sí	RUT cargado en tu cuenta, en formato "12345678-9". También se acepta con puntos.

Ejemplo request con curl

curl -X 'POST' \
  'https://prod.api.thesheriff.cl/api/clients/v3/helper/compliance/76123456-0/actualizarMarshal' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9EjemploDeToken123'

Response

Success (análisis solicitado)

• Status code: 200

• Example response body:

  {
    "success": true,
    "data": {
      "rut": "76123456-0",
      "marshal": true,
      "status": "NO PROCESADO",
      "message": "Se solicitó un nuevo análisis Marshal."
    }
  }

Success (análisis en curso)

Si el RUT ya tiene un análisis Marshal en curso en tu cuenta, no se solicita otro y la respuesta es 200 con este mensaje:

{
  "success": true,
  "data": {
    "rut": "76123456-0",
    "marshal": true,
    "status": "PROCESADO",
    "message": "Ya hay un análisis Marshal en curso para este perfil."
  }
}

Campos de la respuesta:

Campo	Tipo	Descripción
success	boolean	Indica si la solicitud fue aceptada.
data	object	Estado de Marshal para el RUT.

Campos dentro de data:

Campo	Tipo	Descripción
rut	string	RUT consultado, sin puntos (formato "12345678-9").
marshal	boolean	true cuando el RUT queda con Marshal en tu cuenta. Es el mismo valor que compliance.marshal del Resumen.
status	string	"PROCESADO" si el RUT ya tiene algún análisis Marshal completado en tu cuenta, aunque sea anterior; "NO PROCESADO" si no tiene ninguno. Es el mismo valor que compliance.estadoMarshal del Resumen. No indica el estado del análisis recién solicitado.
message	string	"Se solicitó un nuevo análisis Marshal." o "Ya hay un análisis Marshal en curso para este perfil.".

La respuesta es la misma para personas naturales y jurídicas.

Cómo funciona

• Solicita un análisis nuevo aunque el RUT tenga uno completado recientemente. Tu integración decide con qué frecuencia actualizarlo.
• Si ya hay un análisis en curso, una nueva llamada a este endpoint no solicita otro ni valida cupo: verás el resultado de ese análisis. Un análisis está en curso mientras espera la identificación del RUT, está en cola o en proceso (estado EN_CURSO, ver Estados).
• El RUT queda marcado con Marshal en tu cuenta, por lo que compliance.marshal del Resumen pasa a true.
• El análisis se procesa en segundo plano y Sheriff no envía un aviso cuando termina. Para conocer el resultado:
  • Consulta el Resumen de un perfil: compliance.estadoMarshal y el resumen de compliance incorporan el análisis cuando se completa.
  • Consulta el Detalle de Compliance: los hallazgos aparecen en noticias y la detección de PEP, en pepChile.marshal y familiaresPep.marshal.
  • Solicita el webhook de resumen con includeMarshal: true: la entrega espera el análisis en curso hasta por 15 minutos.
  • Consulta Listar investigaciones: la investigación aparece con canal: "API" y puedes seguir su estado.
• Si el análisis falla, se conserva el último análisis completado.

Errores

Además de los errores comunes y los de acceso al RUT, este endpoint puede responder:

400 - RUT inválido

El RUT de la ruta no tiene un formato válido o su dígito verificador no corresponde. Revisa el formato y vuelve a enviar la solicitud.

{
  "success": false,
  "code": 400,
  "error": "El RUT ingresado no es válido. Por favor verifica el formato."
}

400 - corporationId no permitido

La solicitud incluye corporationId, un parámetro que este endpoint no acepta. Quítalo y vuelve a enviar la solicitud.

{
  "success": false,
  "code": 400,
  "error": "No se permite enviar corporationId en la petición."
}

400 / 403 / 503 - Cupo o plan de Marshal

Se devuelven cuando tu plan no permite un nuevo análisis Marshal. Aplican a los planes prepago con bolsa de investigaciones Marshal. No se validan si ya hay un análisis en curso ni si la solicitud incorpora el RUT al monitoreo de Marshal. El mensaje en error indica el motivo y qué hacer:

Código	Cuándo ocurre	Mensaje en error
400	No quedan investigaciones en la bolsa	Has consumido el total de investigaciones Marshal disponibles en tu plan. Escribe al área comercial para solicitar más investigaciones Marshal.
403	El plan no incluye investigaciones Marshal	Tu plan no incluye investigaciones Marshal. Si necesitas esta función, contacta a tu ejecutivo comercial.
403	El plan venció	Tu plan venció. Para renovarlo, contacta a tu ejecutivo comercial.
403	El plan no está vigente	Tu plan ya no está vigente. Contacta a tu ejecutivo comercial para reactivarlo.
503	No se pudo consultar el saldo del plan	No pudimos validar el saldo de tu plan en este momento. Intenta nuevamente en unos minutos.

Por ejemplo:

{
  "success": false,
  "code": 400,
  "error": "Has consumido el total de investigaciones Marshal disponibles en tu plan. Escribe al área comercial para solicitar más investigaciones Marshal."
}

{
  "success": false,
  "code": 403,
  "error": "Tu plan no incluye investigaciones Marshal. Si necesitas esta función, contacta a tu ejecutivo comercial."
}

{
  "success": false,
  "code": 503,
  "error": "No pudimos validar el saldo de tu plan en este momento. Intenta nuevamente en unos minutos."
}

401 - No autorizado

El token no se envió, expiró o no es válido (ver Errores de autenticación). Si expiró, solicita uno nuevo en Obtener Token.

{
  "success": false,
  "code": 401,
  "error": "El token de autenticación no es válido."
}

403 - RUT sin acceso

El RUT existe en Sheriff, pero no está cargado en tu cuenta. Cárgalo con Carga de RUT, donde puedes solicitar el análisis en la misma carga con includeMarshal.

{
  "success": false,
  "code": 403,
  "error": "No tienes permisos para consultar este RUT."
}

403 - Plan sin Marshal

Tu plan no cuenta con Marshal.

{
  "success": false,
  "code": 403,
  "error": "El plan no cuenta con Marshal."
}

403 - Plan sin el ayudante Compliance

Tu plan no incluye el ayudante Compliance.

{
  "success": false,
  "code": 403,
  "error": "El plan no cuenta con el ayudante de compliance."
}

404 - RUT no encontrado

El RUT no existe en Sheriff. Cárgalo con Carga de RUT, donde puedes solicitar el análisis en la misma carga con includeMarshal.

{
  "success": false,
  "code": 404,
  "error": "El RUT consultado no existe en el sistema."
}

422 - Sin razón social

El RUT no tiene una razón social o un nombre válido, que el análisis Marshal necesita. Ese dato se obtiene de la identificación (SII).

{
  "success": false,
  "code": 422,
  "error": "El perfil no tiene una razón social válida para el análisis Marshal."
}

429 - Demasiadas solicitudes

Superaste el límite de solicitudes (ver Rate Limits). Espera los segundos que indica el header Retry-After antes de reintentar.

{
  "success": false,
  "code": 429,
  "error": "Demasiadas solicitudes desde esta API externa, intente más tarde."
}

500 - Error interno del servidor

Ocurrió un error inesperado. Intenta nuevamente más tarde.

{
  "success": false,
  "code": 500,
  "error": "Ocurrió un error interno. Intenta nuevamente más tarde."
}

503 - Solicitud no disponible

No fue posible solicitar el análisis Marshal en ese momento. Vuelve a intentarlo en unos minutos.

{
  "success": false,
  "code": 503,
  "error": "No se pudo solicitar el análisis Marshal. Intenta nuevamente en unos minutos."
}